Note: This is one of three alternative implementations for NEO-1055. See also:

• feat: add useAttribute hook for self-contained property-attribute reflection #97 — Standalone useAttribute hook (self-contained, MutationObserver-based, multi-type support)
• feat: add reflect option to useProperty for property-attribute reflection #100 — reflect option added to existing useProperty hook

Summary

Adds a standalone useAttribute hook for bidirectional boolean property ↔ attribute sync with built-in loop prevention. Addresses NEO-1055.

API

const [opened, setOpened] = useAttribute('opened');

• Boolean-only (v1): attribute present = true, absent = false
• Always reflects: setOpened(true) → setAttribute('opened', ''), setOpened(false) → removeAttribute('opened')
• Dispatches cancelable opened-changed event (same convention as useProperty)
• Supports function updater: setOpened(prev => !prev)
• Supports lift() pattern for parent-controlled state
• Reads initial attribute value from host element
• Respects parent-provided .prop= bindings
• Handles kebab-case ↔ camelCase conversion (open-on-focus → openOnFocus)
• Throws when used in virtual components

Consumer usage

import { component, useAttribute, html } from '@pionjs/pion';

function MyDropdown() {
  const [opened, setOpened] = useAttribute('opened');
  return html`<div>${opened ? 'open' : 'closed'}</div>`;
}

customElements.define('my-dropdown', component(MyDropdown, {
  observedAttributes: ['opened']
}));

// CSS selectors work:    :host([opened]) { ... }
// Declarative HTML:      <my-dropdown opened></my-dropdown>
// Programmatic JS:       dropdown.opened = true
// Query selectors:       document.querySelector('[opened]')

Changes

How it differs from useProperty

Test results

All 81 tests pass (13 new + 68 existing), 96.5% code coverage, zero regressions.